Skip to main content

​
Authentication Methods

UTMStack API supports two authentication methods:
  1. Bearer Token Authentication: Uses username/password to obtain a JWT Bearer token for API requests
  2. API Key Authentication: Uses managed API keys created through UTMStack Settings
Choose the authentication method that best fits your use case and security requirements.

​
Method 1: Bearer Token Authentication

​
Step 1: Authentication Request

Use the /api/authenticate endpoint to log in and receive a Bearer token.
🔧 Request Example: 
curl -X POST https://demo.utmstack.com/api/authenticate \
-H "Content-Type: application/json" \
-d '{"username":"demo","password":"your_password"}'
Make sure to replace the credentials (username and password) with the actual user credentials for your environment.

​
Step 2: Parse the Response

The response will be a JSON object containing the Bearer token, usually under the key id_token or similar, for example: 
{
  "authenticated":true,
  "id_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6..."
}

​
Step 3: Use the Bearer Token

Include the token in the Authorization header when making requests to protected endpoints.
Use the /api/elasticsearch/search endpoint to test your Bearer token authentication.
Request Example: 
curl -X 'POST' \
  'https://demo.utmstack.com/api/elasticsearch/search?page=1&size=25&top=100000000&indexPattern=alert-*&sort=@timestamp,desc' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJkZW1vIiwiYXV0aCI6IlJPTEVfQURNSU4sU...' \
  -d '[
    {
      "field": "status",
      "operator": "IS",
      "value": 2
    },
    {
      "field": "tags",
      "operator": "IS_NOT",
      "value": "False positive"
    },
    {
      "field": "@timestamp",
      "operator": "IS_BETWEEN",
      "value": [
        "now-7d",
        "now"
      ]
    }
  ]'
Response: 
{
  "severity": 3,
  "regDateRulebot": null,
  "severityLabel": "High",
  "notes": "",
  "dataType": "alertEventLog",
  "destination": {
    "country": "India",
    "accuracyRadius": 5,
    "city": "New Delhi",
    "ip": "122.176.80.250",
    "coordinates": [
      28.6320,
      77.2202
    ]
  },
  "port": 63725,
  "countryCode": "IN",
  "subProtocolCategory": "false",
  "alertEventDetailCateg": "utmstack.demo",
  "isSatelliteProvider": false,
  "ago": "Thatti Airtel Ltd. , Telangela Services",
  "user": "Administrator",
  "san": 24505
}
What happens when you don’t include the Authorization header when making requests to protected endpoints.
Request without Authorization: 
curl -X 'POST' \
  'https://demo.utmstack.com/api/elasticsearch/search?page=1&size=25&top=100000000&indexPattern=alert-*&sort=@timestamp,desc' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -d '[
    {
      "field": "status",
      "operator": "IS",
      "value": 2
    },
    {
      "field": "tags",
      "operator": "IS_NOT",
      "value": "False positive"
    },
    {
      "field": "@timestamp",
      "operator": "IS_BETWEEN",
      "value": [
        "now-7d",
        "now"
      ]
    }
  ]'
Response: 
{
  "timestamp": "2025-04-16T16:26:35.664+00:00",
  "status": 401,
  "error": "Unauthorized",
  "path": "/api/elasticsearch/search"
}

​
Method 2: API Key Authentication

API Keys provide a secure alternative to Bearer tokens for programmatic access. They are ideal for integrations, automation scripts, and third-party applications.

​
Step 1: Create an API Key

Before you can use API Key authentication, you need to create an API key in UTMStack:
1

Navigate to Settings

Go to Settings > API Keys in your UTMStack interface.
2

Create New API Key

Click Create API Key and configure:
  • Name: Descriptive name for your integration
  • Expires At: Set expiration date
  • Allowed IPs: Add IP addresses or CIDR ranges (recommended for security)
3

Copy Your API Key

After creation, copy the API key immediately - it will only be shown once!
Store the API key securely. You cannot retrieve it again after closing the dialog.

Complete API Key Management Guide

For detailed instructions on creating, managing, and securing API keys, see the API Keys Management documentation.

​
Step 2: Use the API Key in Requests

Include your API key as a Bearer token in the Authorization header: 
curl -X 'POST' \
  'https://demo.utmstack.com/api/elasticsearch/search?page=1&size=25&top=100000000&indexPattern=alert-*&sort=@timestamp,desc' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY_HERE' \
  -d '[
    {
      "field": "status",
      "operator": "IS",
      "value": 2
    },
    {
      "field": "tags",
      "operator": "IS_NOT",
      "value": "False positive"
    },
    {
      "field": "@timestamp",
      "operator": "IS_BETWEEN",
      "value": [
        "now-7d",
        "now"
      ]
    }
  ]'
The API key is used exactly like a Bearer token - just replace the JWT token with your API key in the Authorization header.

​
Step 3: API Key Response

When using a valid API key, you’ll receive the same successful response as with JWT authentication: 
{
  "severity": 3,
  "regDateRulebot": null,
  "severityLabel": "High",
  "notes": "",
  "dataType": "alertEventLog",
  "destination": {
    "country": "India",
    "accuracyRadius": 5,
    "city": "New Delhi",
    "ip": "122.176.80.250",
    "coordinates": [28.6320, 77.2202]
  },
  "port": 63725,
  "countryCode": "IN",
  "subProtocolCategory": "false",
  "alertEventDetailCateg": "utmstack.demo",
  "isSatelliteProvider": false,
  "ago": "Thatti Airtel Ltd. , Telangela Services",
  "user": "Administrator",
  "san": 24505
}

​
API Key Best Practices

  • Never hardcode API keys in source code
  • Use environment variables or secret management systems
  • Avoid committing keys to version control
  • Store in encrypted configuration or password managers
Always configure allowed IP addresses when creating API keys:
  • Limits access to specific servers or networks
  • Prevents unauthorized use if key is compromised
  • Use CIDR notation for IP ranges
  • Use shorter expiration periods for development (30-90 days)
  • Set longer periods for production (6-12 months)
  • Rotate keys before expiration
  • Remove or regenerate unused keys
  • Regularly review active API keys in Settings
  • Check last used timestamps
  • Monitor for unexpected access patterns
  • Set up alerts for failed authentication attempts
Create separate API keys for different:
  • Applications or services
  • Environments (dev, staging, production)
  • Teams or departments
This limits impact if a key is compromised.

​
Authentication Methods Comparison

FeatureBearer Token (JWT)API Key
Use CaseUser-based authentication, interactive applicationsServer-to-server, automation, integrations
CreationObtained via login credentialsCreated in Settings > API Keys
LifetimeShort-lived, expires after sessionLong-lived, custom expiration date
SecurityUser-specific, session-basedKey-specific, can be restricted by IP
RevocationAutomatic on logoutManual deletion or expiration
Best ForWeb applications, user sessionsAutomated scripts, CI/CD, third-party apps
ManagementAutomaticManual via Settings UI
Recommendation:
  • Use Bearer Token for user-facing applications and interactive sessions
  • Use API Key for backend integrations, automation scripts, and long-running services

​
Official API Documentation

UTMStack provides two official resources where developers can explore and interact with the API:

​
Interactive Swagger UI (Demo Instance)

For hands-on testing and live API interaction, you can explore the Swagger UI provided by the public UTMStack demo instance: https://demo.utmstack.com/swagger-ui/index.html
Each client instance has its own unique Swagger URL, based on how their environment is configured.
Examples:
  • https://<your-company>.utmstack.com/swagger-ui/index.html
  • https://utmstack.<your-domain>.com/swagger-ui/index.html
These tools make it easy to test endpoints, view required parameters, and understand the behavior of the platform’s APIs.